Integrating Cyberhaven with Splunk
This integration allows you to forward events, incidents, and audit logs data from Cyberhaven to your Splunk instance and monitor your data from a centralized location.
The setup process involves the following two steps.
- Create an HTTP Event Collector token in your Splunk instance. 2. Configure an outbound integration in the Cyberhaven Console.
1.Configure HTTP Event Collector
The HTTP Event Collector (HEC) allows you to send data from external applications into Splunk. It uses token-based authentication to receive external data.
Prerequisites
Ensure you have a Splunk index to receive data from Cyberhaven. To categorize the events in Splunk and help you analyze the data easily, create separate indexes, source types, and HEC tokens for each data source (Events, Incidents, and Audit Logs).
Creating a new HTTP Event Collector (HEC)
-
In the Splunk Cloud Console, navigate to Settings -> Data Inputs and select HTTP Event Collector.
-
Click on New Token.
-
Enter a name, the source name, and a description. Click Next.
-
To categorize the events in Splunk, select the destination index and source type you created for this data source.
Cyberhaven sends events in JSON format. So for better organizational searchability, Cyberhaven recommends that you use separate indexes and source types for each data source (Events, Incidents, and Audit Logs).
- Click Review and review your settings. Then, click Submit. The HEC token is created.
Testing the HEC
After creating an HEC token, test that the HEC is receiving messages by running the following command.
macOS
curl "https://http-inputs-my-splunk server.example.com:443/services/collector/raw" \\ \-H "Authorization: Splunk CF179AE4-AYZX-45F5-A7CC-33XXXWW87JI" \\ \-d '{"event": "Hello, world\!", "sourcetype": "manual"}'
Windows
PowerShell
curl "https://http-inputs-my-splunk server.example.com:443/services/collector/raw" \\ \-H "Authorization: Splunk CF179AE4-AYZX-45F5-A7CC-33XXXWW87JI" \\ \-d "{\\"event\\": \\"Hello, world\!\\", \\"sourcetype\\": \\"manual\\"}"
Where, my-splunk-server.exmaple.com is the address of your Splunk server. CF179AE4-AYZX-45F5-A7CC-33XXXWW87JI is an example HEC token. Replace this with your actual HEC token manual indicates the source type.
To view your tokens in the Splunk console, navigate to Settings -> Data Inputs and select HTTP Event Collector.
Configure Outbound Integration in the Cyberhaven Console
To configure the outbound integration in the Cyberhaven Console,
-
Navigate to Preferences -> Integrations and click on Add New in the Destination section.
-
Complete the form as shown in the screenshot. Click Save & Test. When configuring the destination, use the /services/collector/raw endpoint in the URI. This endpoint accepts raw JSON data, which is the format of the events. For example,
https://prdn4b3.splunkcloud.com:443/services/collector/raw -
Next, add a new configuration in the top section of the page. Click Add New.
-
Complete the form as shown in the screenshot. You can select the source as Events, Incidents, or Audit. As mentioned above to aid in filtering on in Splunk it is recommended to send one source type to each destination configured.
-
Click Save. The configuration takes a few minutes to start sending the data.
Troubleshooting
The following are a few of the common errors and troubleshooting steps.
| Issue/Error | Troubleshooting Steps |
|---|---|
| connect: no route to host | Check network connectivity between the sensor and the HEC endpoint |
| tls: failed to verify certificate: x509: certificate is not valid for any names | Verify TLS certificate configuration. If you are testing in a sandbox, select Ignore SSL errors in the Destination configuration |
| 404 Not Found Header | Send a test message to the HEC. If it fails, check IP whitelisting under Server Settings IP Allowlist. If it succeeds, verify the URI and authorization header |
Integrating Cyberhaven with SIEM Tools Using Scripts (Legacy API v1)
NOTE
This integration method uses the legacy API v1. If you are setting up this integration for the first time, use the workflow described in Cyberhaven Integration Workflow Best Practices Guide .
Incidents can be retrieved by running a script. There are two script files, start_monitoring.sh and siem-monitor-incidents.py .
The start_monitoring.sh uses Cyberhaven's authentication token to call siem-monitor-incidents.py which uses the API endpoint,
/api/rest/v1/incidents/list to poll for incidents in Cyberhaven's dashboard. The list of incidents is displayed in your terminal window.
You can configure your SIEM tool to ingest the output from your standard terminal window.
Using the script to poll for incidents
To run the script, start_monitoring.sh you need an API token and the hostname from your Cyberhaven tenant URL.
-
Login to the Cyberhaven dashboard and go to Preferences > API token management to create an API token.
-
Copy the API token to a notepad. Also, copy the hostname from your Cyberhaven tenant URL to the notepad.
Example
If your Cyberhaven tenant URL is
https://mycompany.cyberhaven.io/, then your hostname is
mycompany.cyberhaven.io.
- Create a local folder and copy the two scripts, start_monitoring.sh and siem-monitor-incidents.py into the folder.
start_monitoring.sh
Copy the following text into a notepad, enter the API token and hostname from step 2, then save the file as start_monitoring.sh to the folder you created.
PowerShell
\#\!/usr/bin/env bash \# this script polls incidents at the specified interval and outputs results to console \# python script is a single-run script, you must manage intervals and failures externally AUTH="eyJlbW......." HOST="mycompany.cyberhaven.io" INTERVAL\_SECONDS=1 while python3 siem\-monitor\-incidents.py $AUTH $HOST; do sleep $INTERVAL\_SECONDS; done
siem-monitor-incidents.py
To obtain the Python script, you can download the latest version:
| Bash | Copy |
|---|---|
| curl https://storage.googleapis.com/files.cyberhaven.io/su pport/siem-monitor-incidents.py --output siem monitor-incidents.py |
Move the resulting siem-monitor-incidents.py to the same folder as start_monitoring.sh . The script is also available below for reference.
Python Copy # Siem script
This script will log alerts about incidents found by Cyberhaven. You can use it to connect Cyberhaven
Lightbeam with your SIEM.
You can run this script as such:
- bash script,
- cron job,
- scripted source
https://docs.splunk.com/Documentation/SplunkCloud/8.0 .0/AdvancedDev/ScriptSetup
Before using the script, you should:
- Add the auth token into start_monitoring.sh
script.
- Point HOST variable to your Cyberhaven hostname. 3. Start the script as bash script using
./start_monitoring.
# Customization
You might want to run the script as cron job or as scripted input in splunk.
In this case you have to run your script like
python3 siem\-monitor\-incidents.py $AUTH $HOST
Replaying custom events
To replay custom events you have to pass additional parameter to python script '--replay-old', it will replay all the pre existing events and output them to console
import argparse
import base64
import copy
import json
import logging
import os
from datetime import datetime, timedelta
import requests
parser = argparse.ArgumentParser(
description='Fetches Cyberhaven incidents and
logs them')
parser.add_argument("auth", help\="base64 encoded
credentials", type\=str)
parser.add\_argument(
"host", help\="hostname format \`example.com\`
without protocol", type\=str)
parser.add\_argument(
"--replay-old", help\="replay already existing
incidents", default\=False, action\='store\_true')
parser.add\_argument(
"--no-verify", help\="allow insecure requests",
default\=False, action\='store\_true')
args \= parser.parse\_args()
AUTH\_PATH \= "/user-management/auth/token"
ALERTS\_PATH \= "/api/rest/v1/incidents/list"
AUTH \= args.auth
HOST \= args.host
API\_PATH \= "https://"\+HOST
REPLAY\_OLD \= args.replay\_old
\# verify ssl certificate
VERIFY \= not args.no\_verify
nowTimeISO \= datetime.utcnow().isoformat() \+ "Z"
\# if we replay old events then start set day to
something in the past
if args.replay\_old:
nowTimeISO \= "2001-01-01T00:00:00Z"
\# incidents default request data
incidents\_request\_data \= {
\# amount of entities to fetch
"page\_size": 10,
"sort\_desc": False,
"sort\_by": "event\_time",
"filters": {
"times\_filter": {
"end\_time": "2090-09-01T23:59:59Z",
"start\_time": nowTimeISO
}
}
}
logging.basicConfig(level\=logging.INFO)
def authenticate\_request(base64\_creds):
"""request to fetch auth token"""
creds\_json \=
base64.decodebytes(bytes(base64\_creds, 'utf8'))
creds \= json.loads(creds\_json)
r \= requests.post(url\=API\_PATH \+ AUTH\_PATH,
verify\=VERIFY,
data\=creds, headers\={'HOST':
HOST})
r.raise\_for\_status()
return r.content.decode("utf-8")
def incidents\_request(token, start\_time, size,
search\_after \= ""):
"""
request to fetch incidents
token is authentication token returned by auth
request
page\_id is pagination cursor
"""
request\_data \=
copy.deepcopy(incidents\_request\_data)
request\_data.update({'page\_id': search\_after, 'page\_size': size })
request\_data\["filters"\]\["times\_filter"\]
\["start\_time"\] \= start\_time
auth\_header \= 'Bearer {}'.format(token)
r \= requests.post(url\=API\_PATH \+ ALERTS\_PATH, json\=request\_data,
verify\=VERIFY,
headers\={'authorization':
auth\_header, 'content-type':
'application/json;;charset=UTF-8'})
if r.status\_code \== 401:
print("Not authenticated")
if r.status\_code \>= 400:
print(r.text)
exit(0)
json\_data \= r.json()
records \= json\_data.get("incidents", None)
return {
'alerts': records,
'next\_page\_id': json\_data.get('next\_page\_id',
'')
}
def format\_event(event):
source\_edge \= event\['edge'\]\['source'\]
destination\_edge \= event\['edge'\]\['destination'\]
eventid \= event\['id'\]
search\_name \= "Dataset: {}, Category:
{}".format(event\['category'\]\['name'\],
event\['dataset'\]\['name'\])
file\_name \= 'none'
if 'path\_basename' in source\_edge.keys(): file\_name \= source\_edge\['path\_basename'\]
source\_location \= source\_edge\['location\_outline'\] source\_type \= source\_edge\['location'\]
destination\_location \=
destination\_edge\['location\_outline'\]
destination\_type \= destination\_edge\['location'\]
date \= destination\_edge\['local\_time'\]
user \= destination\_edge.get('local\_user\_name',
'none')
event\_type \= destination\_edge\['event\_type'\]
hostname \= 'none'
if 'hostname' in destination\_edge.keys():
hostname \= destination\_edge\['hostname'\]
return json.dumps({
'id': eventid,
'search\_name': search\_name,
'file\_name': file\_name,
'source\_location': source\_location,
'source\_type': source\_type,
'destination\_location': destination\_location,
'destination\_type': destination\_type,
'date': date,
'user': user,
'event\_type': event\_type,
'hostname': hostname
})
def log\_events(events):
for event in events:
data \= format\_event(event)
print(data)
class LastIncidentObjectPersisted:
current \= ''
file \= None
def \_\_init\_\_(self, path):
self.path \= path
mode \= 'r+' if os.path.exists(path) else 'w+'
self.file \= open(path, mode)
self.current \= self.file.read()
def get(self):
"""return persisted value"""
strippedValue \= self.current.strip()
data \= strippedValue.split("\_", 1\)
search\_after \= ""
start\_time \= ""
if len(data) \>= 1:
start\_time \= data\[0\]
if len(data) \== 2:
search\_after \= data\[1\]
return {
'search\_after': search\_after,
'start\_time': start\_time
}
def set(self, start\_time, search\_after):
"""set value to file"""
formatedValue \= "{}\_{}".format(start\_time,
search\_after)
self.file.seek(0)
self.file.truncate(0)
self.file.write(formatedValue)
os.fsync(self.file)
self.current \= formatedValue
one\_ms \= timedelta(0, 0, 1000\)
def parse\_nano\_date(str):
arr \= str.replace("Z", "").split(".")
d \= datetime.fromisoformat(arr\[0\])
if(len(arr) \> 1):
ms \= int(arr\[1\]\[0:6\])
d \= d.replace(microsecond\=ms)
return d
def main():
token \= authenticate\_request(args.auth)
script\_dir \=
os.path.realpath(os.path.join(os.getcwd(),
os.path.dirname(\_\_file\_\_)))
last\_incident\_id\_store \=
LastIncidentObjectPersisted(os.path.join(script\_dir, './incidents.state'))
persisted\_value \= last\_incident\_id\_store.get()
if persisted\_value\['start\_time'\] \== "":
last\_incident\_id\_store.set(nowTimeISO, '')
persisted\_value\['start\_time'\] \= nowTimeISO
events \= incidents\_request(token,
persisted\_value\['start\_time'\], size\=30,
search\_after\=persisted\_value\["search\_after"\])
log\_events(events\["alerts"\])
if events\["next\_page\_id"\] \== '' and
len(events\['alerts'\]) \> 0:
\# take date, remove Z at the end and add one
second and then bring back Z at the end
\# api and python iso formats are different
\# in case we reached end of the list we want
to store time of last event and use it in order to continue pagination
d \= parse\_nano\_date(events\['alerts'\]\[\-1\]
\['event\_time'\]) \+ one\_ms
result\_date \= d.isoformat() \+ "Z"
last\_incident\_id\_store.set(result\_date,
events\["next\_page\_id"\])
else:
last\_incident\_id\_store.set(persisted\_value\['start\_tim e'\], events\["next\_page\_id"\])
if \_\_name\_\_ \== '\_\_main\_\_':
main()
4. Open a terminal window, navigate to the folder containing the two scripts and run ./start_monitoring.sh .
The script returns a list of incidents based on the polling interval defined in start_monitoring.sh . Each incident contains a unique ID of the incident, the alert name that generated the incident, and metadata for the source and destination of the flow of data that generated the incident.
Script Output Field Descriptions
The table below lists all the incident fields that the script output displays in the terminal.
| Fields | Description |
|---|---|
| id | An identifier that was assigned by Cyberhaven for the incident. |
| search_name | The dataset and policy name. |
| file_name | The file name of the flow that triggered the incident. |
| source_location | The type of source location of the matching data flow, for example, endpoint, website, etc. |
| source_type | A short outline of the source location that triggered the incident such as node, hostname for endpoint, email for cloud, device name for removable media. |
| destination_location | The type of destination location of the matching data flow, for example, endpoint, website, etc. |
| destination_type | A short outline of the destination location that triggered the incident such as node, hostname for endpoint, email for cloud, device name for removable media. |
| date | The date of the event that triggered the incident. |
| user | The username that triggered the incident. |
| event_type | The type of event that led to data arriving at / leaving from a location. |
| hostname | The hostname of an endpoint/share where data resides. |
Metadata Field Descriptions
The table below lists all the metadata we collect for the source and destination.
| Fields | Description |
|---|---|
| Data | |
| data.app_commandline | The command line that started the application for accessing the data. |
| data.app_description | The description of the application used to access the data. |
| data.app_main_window_title | The title of the main application window. |
| data.app_name | The name of the application used to access the data. |
| data.app_package_name | The package name for Modern Windows applications. |
| :---- | :---- |
| data.blocked | A flag indicating whether the event was blocked. |
| data.browser_page_domain | The domain extracted from the referrer URL. |
| data.browser_page_title | The page title of the website |
| data.browser_page_url | The referrer URL. |
| data.category | The type of website, for example, webmail, social media, etc. |
| data.cloud_app | The type of cloud application, for example, OneDrive, SharePoint, Google Drive, etc. |
| data.cloud_app_account | The user account used to log in to the website. |
| data.cloud_provider | The type of cloud provider storing data, for example, Office 365, Salesforce, etc. |
| data.comment | The device description, such as a printer as provided by the admin user. |
| data.content_uri | For email retrieved by the cloud sensor, the URI of the attachment in O365 servers. |
| data.data_size | The size of a piece of data, for example, when copy and pasted. |
| data.device_physical_location | The physical location such as, the building or room where the device is stored. Examples of devices are printers, scanners, etc. |
| data.domain | The domain name, in the form .sub.domain.tld. |
| data.domain_components | The domain name split into domain components. |
| data.driver | The printer device driver, if applicable. |
| data.email_account | The email address that identifies the mailbox where the data resides. |
| data.email_groups | The geographic location of the email account. |
| data.email_subject | The subject of the email where the data resides. |
| data.endpoint_id | The identifier for the endpoint where the event was generated. |
| data.event_type | The type of event that led to data arriving or leaving a location. |
| data.extension | The file type or the extension of the file. |
| data.file_size | The size of a file in bytes. |
| :---- | :---- |
| data.group_name | The list ofActive Directory groups to which the user accessing the file belongs. |
| data.hostname | The hostname of an endpoint or share where the data resides. |
| data.job_name | Print job name. |
| data.local_file_id | The ID of a file on an endpoint/network share/cloud storage. For local files on endpoints/shares, the file ID is obtained by concatenating the Volume Serial Number and the File ID provided by the file system, in the form volume_serial_number;file_id. |
| data.local_groups | The list ofActive Directory groups to which the user accessing the file belongs. |
| data.local_machine_name | The hostname of the machine where the event happened. |
| data.local_time | The time when the data arrived in the silo. |
| data.local_user_name | The username of the user accessing the data. |
| data.local_user_sid | The SID of the user accessing the data. |
| data.location | The type of location where data resides, for example, endpoint, website, etc. |
| data.location_outline | A short outline of the location that triggered the incident. For example, node, the hostname of the endpoint, email, and device name of removable media. |
| data.md5_hash | The MD5 hash of a file at a location. |
| data.media_category | The type of removable media. |
| data.path | The path where the data being accessed resides or, in the case of EndpointApps, where the application resides. |
| data.path_basename | The file name retrieved from the file path. |
| data.path_components | The path to a file split in a sequence of folders. |
| data.port | The device port name. For example, if the device is a printer, then the port names are LPT, USB, etc. |
| data.printer_name | The name of the printer. |
| data.quick_xor_hash | The quick XOR hash of a file at a location. |
| data.removable_device_id | The unique ID of the removable device. |
| ----- | :---- |
| data.removable_device_name | The name of the removable device. |
| data.removable_device_product_id | The 16-bit number assigned to specific USB device models by the manufacturer. |
| data.removable_device_usb_id | The unique hardware ID of the removable media. |
| data.removable_device_vendor_id | The 16-bit number assigned to USB device manufacturers by the USB Implementers Forum. |
| data.salesforce_account_domains | Salesforce domain name from user’s email address. |
| data.salesforce_account_name | Name of the Salesforce account. |
| data.url | The exact URL used to access the data. |
| Category | |
| category.dataset_ids.exclude_origin | (For review) When “true” this field indicates that “Exclude flows to datasets origin” is enabled in the policy. |
| category.dataset_ids.name | Name of the policy that matched the activity. |
| category.rule | Object for category rules configuration. |
| category.rule.allow_request_review | When “true” this field indicates that “Allow the user to request a policy review” is enabled in the response message of the policy. |
| category.rule.create_incident | When “true” this field indicates that “Create an incident” is enabled in the policy. |
| category.rule.incident_action | The action to be taken when a policy match occurs such as, Warn, Block, or Nothing. |
| category.rule.notify_email | The email address to which the incident notification is sent. |
| category.rule.notify_enabled | When “true” this field indicates that “Send email notifications” is enabled in the policy. |
| category.rule.override_enabled | When “true” this field indicates that “Allow user to override blocking” is enabled in the response message of the policy. |
| category.rule.require_justification | When “true” this field indicates that the user is required to provide a justification. |
| category.rule.should_ack_warning | When “true” this field indicates that the user is required to acknowledge a warning. |
| category.rule.show_logo | When “true” this field indicates that a logo was uploaded to be shown in the response message. |
| :---- | :---- |
| category.rule.show_title | When “true” this field indicates that “Show the dialog title” is enabled in the response message of the policy. |
| category.rule.status | The risk level assigned to the data that matches the policy such as, High, Low, or Trusted. |
| Dataset | |
| dataset.name | Name of the dataset that identifies the category of data that matched the policy. |
| File | |
| file | The name of the original file for the data flow that triggered the incident. |
| Incident Reactions | |
| incident_reactions | The user’s reaction to an incident or a response message if applicable. |
| Incident Response | |
| incident_response | The policy’s response to a user action that triggered the incident. For example, Warning shown, Provided an explanation. |
| Resolution Status | |
| resolution_status | The incident resolution status that was set by an administrator or operator such as Assigned, Ignored etc. |
Integrating Cyberhaven with Splunk Using the App (Legacy API v1)
NOTE
The Integrations feature replaces this legacy solution. If you are setting up this integration for the first time, use the workflow described in Cyberhaven Integration Workflow Best Practices Guide.
Splunk integration enables you to monitor incidents generated by Cyberhaven Sensors in your Splunk dashboard. To integrate with Splunk you must,
1. Download the Cyberhaven app from Splunk Apps.
2. Authorize Cyberhaven in Splunk to receive incident data.
Download the Cyberhaven app
1. Login to your Splunk instance: on-prem or cloud app.
2. Click on “Find More Apps”, in the left panel.
3. Search for Cyberhaven Splunk application and click Install.
Authorize Cyberhaven in Splunk
1. When the installation is complete, go to the Search tab and enter a new search, index="cyberhaven" to search for the app. On the Inputs page, click Create New Input.
2. In the Add Incidents script dialog box, provide the input parameters. The following image is an example script.
3. To get your Auth token and Host url,
a. Browse to the following URL.
https://\<instance-name\>.cyberhaven.io/api-tokens
b. Click on “CREATE NEW TOKEN” and give it a name (for
example, splunk integration as shown in the screenshot below). c. Click on “CREATE”. Cyberhaven creates an API token which is the Auth Token.
d. Copy the token to the clipboard and close this window.
4. Go back to the Add Incidents script dialog box in your Splunk instance and do the following:
a. Enter the host URL as <your-instance-name>.cyberhaven.io. b. Paste the Auth Token you copied in the previous step.
c. Click Add.
The new data input is displayed on the Inputs page.
5. Go to the Search tab. In the New Search text box, search for the following:
index="cyberhaven"
Alist of all the incidents from the Cyberhaven Console will now be available on your Splunk dashboard.
Viewing Incidents in Splunk
Log in to the Splunk dashboard to view all the incidents generated on the Cyberhaven Incidents page. New incidents from Cyberhaven are automatically added to the Splunk dashboard. You can refresh the page or run the search query to get the latest list of incidents.
Since the Cyberhaven Splunk application can process a high load (like million incidents per minute), incidents are displayed within a minute after they are displayed on the Cyberhaven Incidents page.
Incident Severity
Aseverity rating is assigned to each incident based on the severity rating you chose for the Cyberhaven policy. Starting with Cyberhaven Console v23.03, policies have additional severity ratings. Cyberhaven assigns a value to each rating that will be used to calculate the risk score in the upcoming risk management tools.
Policies have the following five severity ratings.
| Severity Rating | Value |
|---|---|
| Critical | 4 |
| High | 3 |
| Medium | 2 |
| Low | 1 |
| Informational | 0 |
In the Splunk dashboard, the severity ratings of the incidents are classified as "risky" for High severity incidents and "low_risky" for Low severity incidents. With the addition of new severity ratings in the Cyberhaven Console v23.03, incidents are generated for all severity levels.
NOTE
Due to the policy severity rating enhancements, newly reported incidents on the dashboard will be assigned a severity rating of "risky".
Incident fields
The incident fields in the Splunk dashboard include all the fields that can be exported from the Cyberhaven Incidents page as well as the fields defined in the Common Information Model (CIM).
Read more: https://docs.splunk.com/Documentation/CIM/4.2.0/User/Alerts Cyberhaven sends the following list of CIM fields to Splunk.
'app': format_value(destination_edge.get('app_name')),
'body': format_value(content),
'dest': format_value(destination_location),
'dest_category': format_value(event.get('category').get('id')), 'src': format_value(source_edge.get('hostname')),
'src_bunit': format_value(source_edge.get('location')),
'src_category': format_value(source_edge.get('event_type')),
'src_priority': format_value(source_edge.get('event_type')),
'subject': format_value(event.get('category').get('name')),
'tag': format_value(",".join(event['content_tags'] or [])),
'type': format_value(destination_edge.get('event_type')),
Additionally, the following fields from the Incidents page are sent to Splunk.
None Copy
assignee
resolution_status (filter: unresolved)
dataset_name
category_severity
category_name
user
file
content
content_tags
response
user_reaction
explanation
resolved_by
timestamp UTC
reaction_time UTC
resolution_time UTC
app_name
app_main_window_title
app_package_name
app_description
app_command_line
blocked
browser_page_url
browser_page_domain
browser_page_title
content_uri
cloud_provider
cloud_app
data_size
domain
domain_category
event_type
endpoint_id
email_account
email_groups
destination_file_path
source_file_path
file_extension
file_size
group_name
hostname
location
local_time UTC
local_user_name
local_user_sid
local_groups
local_machine_name
media_category md5_hash
salesforce_account_name
salesforce_account_domains
printer_name
removable_device_name
removable_device_vendor_id
removable_device_product_id
url
Limitations
1. If incidents do not appear right away on the Cyberhaven Incidents page, they will not appear in the Splunk dashboard either.
2. The cloud version of the Splunk App takes longer to update compared to the desktop version of the Splunk App. The desktop and cloud versions of the Cyberhaven Splunk application are available here.
Troubleshooting
1. If no events are showing up in your Splunk app, then check that you
entered the correct Auth Token. If the token is incorrect, then remove the Cyberhaven Splunk application, download, and set up the app again. 2. It is possible to search for debug logs locally. In the Splunk UI, go to the Search tab and enter the following search queries in the New Search text box.
| None | Copy |
|---|---|
| index="_internal" "incidents" index="_internal" "siem" |
Cyberhaven Integration Workflow Best Practices Guide
The Cyberhaven platform is integrated into the data workflows of our customers' environments and delivers visibility and control over the data-in-motion activity that is occurring.
To achieve this, Cyberhaven connects separate events into a data lineage and uses this information to provide classification based on historical characteristics and activity of the data moving around a customer's environment. Built on top of lineage tracing capability, Cyberhaven provides policy options to record events of interest or perform actions to manage user behavior.
As a result, the Cyberhaven platform provides you with two valuable data sources: incidents recorded from user activities, and data lineage that includes the individual events, which can be reviewed to further investigate the user activity.
Cyberhaven will often represent one element of a customer’s security ecosystem, where the aggregated data from various other systems aid in the investigation and understanding of events or behaviors that are observed. Therefore, it is essential to extract vital information generated by Cyberhaven and integrate it with systems that can be used to accumulate security telemetry and provide workflows for customers, such as SIEM or SOAR platforms. This document will help to establish the expected mechanisms for accessing this information via the integration capabilities of the Cyberahven platform.
Cyberhaven Integrations
Outbound Integrations
The integration capability of the Cyberhaven platform enables you to configure outbound integrations with one or more destination locations along with a corresponding profile where you can specify the relevant information you want to send to those destinations. The outbound integration is intended to support customers' investigative workflows and regulatory compliance. By utilizing outbound integrations, customers can send relevant information to necessary destinations to aid their investigations or to store data in external locations as part of their compliance processes.
The configuration of integrations is divided into two sections to allow specific configurations for individual elements while allowing you to reuse destinations (for example) for multiple data sources.
Configuring Outbound Integrations
To add a new integration there are some prerequisite requirements. The Cyberhaven user must have the following:
Admin access to the integration capability. This access is provided in the global admin role or with the specific permissions for integration destination, integration configuration, and integration connection history in the Settings section of a user’s role.
Details of the integration destination.
URL for the integration destination. Currently, only HTTPS is
supported.
Authentication requirements for the destination. This could be a username and password or an authentication token.
Requirements to send the source information to the destination. Currently, you can send Incidents and Audit logs by default. As a separate option, you can choose to send bulk event information. This capability operates on a separate platform, so contact your Cyberhaven sales representative to discuss this capability.
Adding a new destination
1. Navigate to Settings > Integrations in the Cyberhaven Console and then select Add New under Destinations in the lower section of the page.
2. Complete the form with the required information.
At this time only HTTPS destinations are supported.
The format can be JSON or JSON Lines.
JSON - Sends a single JSON object of the type specified
in the configuration to the destination, which includes an
array of events inside the resources object of the JSON.
JSON Lines - Sends multiple JSON objects to the
destination simultaneously, with each object separated by
a new line. This format is known as NDJSON or JSON
lines. Support for this format is available from version
24.10.
If the destination system uses a self-signed certificate then enable the option Ignore SSL Errors.
NOTE
The “Ignore SSL Errors” option should be used for testing
purposes only and is not recommended to be used for
production integrations.
If the destination requires authentication (which is recommended) then configure the required settings in either the Authentication or HTTP headers options. The destination will provide you with
these options. For example, when utilizing Splunk HTTP Event Collector (HEC) the “HTTP HEADERS” fields would be populated as shown below.
3. When finished, click Save and Test. This button will commit the configuration and perform an initial HTTP POST check to the destination to validate connectivity. You must troubleshoot and resolve any connection issues before data can be sent from the Cyberhaven platform.
Adding a new configuration
To utilize the configured destination you need to create a configuration and
select the information to be sent from the Cyberhaven platform.
1. Click Add New in the Configurations section at the top of the Integrations page.
2. Complete the form with the required information.
3. Give the configuration a name and select a previously configured destination.
4. Select a data source from the list of available sources in the Cyberhaven platform. The configuration uses the data source to send the required information to the destination.
At this time there are two default sources:
Incidents - This data source sends notifications when incidents are created in the Cyberhaven platform. It generates a new
incident object for every incident created in the platform.
Audit - This data source sends audit events generated in the
Cyberhaven platform as seen on the Audit log page of the
Cyberhaven Console.
Events - This data source sends all data-in-motion events
captured by the Cyberhaven platform. “Events” is an additional
source available as a separately licensed feature of the platform along with another feed. This source is separate due to the very large volume of data generated from all the events captured by
the platform.
5. Set the schedule for sending the data. Currently, there is only one schedule available which is Immediate. The Cyberhaven platform will push the data to the destination at regular intervals, based on the rate at which events are generated, or at an interval less than 1 minute.
6. The configuration is enabled by default. This setting allows you to create a configuration and disable it until you have set up other applications, such as the receiver or firewall.
When the configuration is complete the Cyberhaven platform will start sending events on a regular basis to the selected destination.
For examples of payloads received from Cyberhaven, see Sending Payload. Troubleshooting
Connectivity issues
If the connection to the destination is interrupted the Cyberhave platform will buffer events for some time. (The total number of events buffered is not predictable. It is based on the rate at which events are generated and the downtime of the connection).
You can receive these events when the connectivity is re-established using the Resend undelivered option in the settings of that configuration.
To help you troubleshoot connectivity issues, the Cyberhaven platform also maintains a connection log that provides information about any failure to establish connections. Click on See connection history.
Cyberhaven API
The Cyberhaven external API (also referred to as API v.2) is available to all customers and can be used to make both configuration and query actions
against the platform as part of integrations with other platforms like SIEM and SOAR.
API Authentication
APIs can be accessed using API keys that are managed inside the platform. To create or manage a key,
1. In the Cyberhaven Console, navigate to Settings > Users & API keys. 2. Select New API Key and complete the form shown below. 3. Enter a key name. The key name will be used to identify the key in the platform’s audit logs. Therefore, we recommend selecting a name that identifies the use of the key.
4. Select a role. The available API key roles are:
API Global admin - Access to all permissions possible with the API. The permissions cannot be modified.
API Admin - Access to all permissions possible within the API. This role can be configured to change or remove permissions. 5. Select a date range during which the API key is valid. The lifetime of the key is determined by the start and end dates. As a security best practice, the duration cannot exceed one year.
6. Click Save. The key is displayed only once and cannot be seen again. If you lose access to the key then the only solution is to revoke the old key and create a new one with the appropriate permissions.
Documentation
The documentation and specifications for the APIs are hosted in the Cyberhaven Console and can be accessed under Administration > API Specification.
The documentation page provides information on the available services and routes that can be utilized. It also includes a testing capability to validate the output of events from the API within the Console, allowing for easy comparison to those events seen in the UI.
To test any API routes on the API specification page you must first authenticate using the Token option located at the bottom of the page. This process requires the API token you previously created which generates a temporary access token for submitting queries to the other routes.
For detailed instructions, see APIAuthentication.
To test the route, complete the example field. Include the API token and then use the Try button to submit the API request. As shown in the screenshot, a successful response will display an access token which is then used to submit requests to the remaining test API routes.
When the request is successful, the response status will show an HTTP success response code of 200 and the response message will include the provided access token. This is then cached in the UI to be used in the remaining test pages.
To use the APIs in external integrations, you must follow the same process. First, submit an authentication token and then reuse the returned access token with future requests to the API.
The documentation includes every API route and its supported options along with a schema the outlines the required query parameters, if applicable, in the request section, and the response objects returned in the response section.
Integrations Workflows
Incidents to Events to Lineage
The integration workflow for incidents and events is designed to manage the large volume of data generated by the platform. It ensures that event data is collected only when it is relevant to incidents, reducing the amount of information sent by the platform to the destination system to a manageable level.
Currently, the incidents in the Console include a link to all the related events that were generated from the beginning of the tracking period up to the event that triggered the incident, which could include hundreds of events. Although, only a subset of the events would be useful when triaging an incident.
To establish this link between the incident and their associated events, Cyberhaven sends two event IDs with each incident report through the configured integration. These event IDs are included in the incident JSON object as end_event_id and start_event_id within the event_lineage_id object.
To gather the events shown in the UI as the lineage associated with an incident, use the following two APIs. You need both APIs to get all the required information.
/v2/event-lineage - This API takes the two event IDs from the incident and returns a list of events that connect those two IDs. The result could be a large list of event IDs that represent the connected events between the two IDs.
/v2/event-details - After getting the list of event IDs from the
/v2/event-lineage API, this API returns detailed information for each event ID. The volume of data returned can be very large since there could be many events in the list and each event may include a substantial amount of information.
Recommendation
When gathering event information for an incident, Cyberhaven recommends that you initially focus only on the two event IDs returned by the incident. To do this, query the event-lineage API as mentioned above using the two event IDs.
This approach will provide information about the first event in the lineage that started the classification process and then the event that triggered the incident. These two events will provide insight into the reason the incident was created.
If the incident requires further investigation, then use the two-step API process: first retrieve the list of event IDs using the event-lineage API and then get details information for each event with the event-details API. This process will give you a full view of the event lineage in the external system.
API v1.0
Cyberhaven’s Open APIs implementation enables customers to integrate
Cyberhaven with key enterprise tools such as SIEMs, SOAR, ticketing, and asset management tools. The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. The following endpoints are included:
Endpoints (/api/rest/v1/endpoints/list)
Incidents (/api/rest/v1/incidents/list)
Dataflow (/api/rest/v1/audit-log/dataflow/list)
See the complete API documentation to learn more. The documentation is available at the following location.
https://storage.googleapis.com/cyberhaven-docs/redoc
static.html#/paths/~1api~1rest~1v1~1endpoints~1list/post
Configure the API Endpoints
To configure and call the API endpoints you must do the following:
1. Generate a refresh token
2. Generate short-lived tokens using the refresh token
1. Generate refresh token in the Cyberhaven dashboard
Login to the dashboard and go to the /api-tokens page and create an API token:
This is your static refresh token that you can use to generate short-lived tokens.
2. Generate a short-lived token
Run this command in a bash environment with curl available. This can be done in the terminal window:
REFRESH_TOKEN=#tokenfromui
DEPLOYMENT=domain.cyberhaven.io
TOKEN=$(echo $REFRESH_TOKEN | base64 -Dd | xargs -0 -I curl -H 'content-type: application/json' https://$DEPLOYMENT/user-management/auth/token -k --data '')
Check if the API works by querying the available endpoints.
curl -H 'content-type: application/json' -H "Authorization: Bearer $TOKEN" https ://$DEPLOYMENT/api/rest/v1/endpoints/list -k --data ''
Here is a full script you can use:
REFRESH\_TOKEN="get your token from /api-tokens"
DEPLOYMENT=your\_deployment.cyberhaven.io
TOKEN=$(echo $REFRESH\_TOKEN | base64 \-Dd | xargs \-0 \-I{} curl \-H 'content-type: application/json' https://$DEPLOYMENT/user-management/auth/token \-k \--data '{}')
curl \-H 'content-type: application/json' \-H "Authorization: Bearer $TOKEN" https ://$DEPLOYMENT/api/rest/v1/endpoints/list \-k \--data '{}'
Endpoint Status API Use the REST API endpoint, /api/rest/v1/endpoints/list to view the status of all your Endpoint Sensors. Read the documentation for detailed information about the output response. The following table provides a complete list of Sensor statuses and their corresponding descriptions. Status Status (Healthy / Requires Attention / Inactive) Status Details (New ActionText) Status Details Text (New Description) Max size 500 characters
| chrome_extension_has_policy_conflict | Requires Attention | Chrome extension policy conflict | Cyberhaven Chrome browser extension conflicts with a user-level extension policy. As a result, the extension was not installed. |
|---|---|---|---|
| chrome_extension_needs_update | Requires Attention | Outdated Chrome extension | This endpoint is not running the latest browser extension, indicating that auto-updating may be disabled. Enable extension auto-updating or manually deploy the latest version. |
| chrome_extension_v3_needs_update | Requires Attention | Outdated Chrome extension | This endpoint is not running the latest browser extension, indicating that auto-updating may be disabled. Enable extension auto-updating or manually deploy the latest version. |
| firefox_extension_needs_update | Requires Attention | Outdated Firefox extension | This endpoint is not running the latest add-on, indicating that auto-updating may be disabled. Enable add-on auto-updating or manually deploy the latest version. You may need to restart Firefox after installing Cyberhaven. |
| file_was_modified | Requires Attention | Compromised Sensor integrity | The Sensor detected that one of its files was modified. Check that the Sensor paths are excluded in any EDR tools and reinstall. |
| file_was_renamed | Requires Attention | Compromised Sensor integrity | The Sensor detected that one of its components was renamed. Check that the Sensor paths are excluded in any EDR tools and reinstall. |
| file_was_deleted | Requires Attention | Compromised Sensor integrity | The Sensor detected that one of its components was deleted. Check that the Sensor paths are excluded in any EDR tools and reinstall. |
| integrity_check_error | Requires Attention | Compromised Sensor integrity | The Sensor files may have been corrupted. Reinstall the Sensor. |
| general_update_required | Healthy | Update pending | The Sensor version does not match the update policy. |
| win_uninstall_success | Inactive | Uninstalled Sensor | The Sensor on this endpoint was not password protected and was uninstalled. |
| msedge_extension_has_policy_conflict | Requires Attention | Edge extension policy conflict | Cyberhaven Edge browser extension conflicts with a user-level extension policy. As a result, the extension was not installed. |
| msedge_extension_needs_update | Requires Attention | Outdated Edge extension | This endpoint is not running the latest browser extension, indicating that auto-updating may be disabled. Enable extension auto-updating or manually deploy the latest version. |
| service_was_stopped | Requires Attention | Sensor stopped | The Sensor is no longer running because the Cyberhaven service was stopped. Check that the Sensor paths are excluded in any EDR tools and restart the Cyberhaven service. NOTE: This status does not indicate the current state of the Sensor. |
| uninstall_success | Inactive | Uninstalled Sensor | The Sensor was not password protected and was uninstalled. |
| service_stopped_by_config | Inactive | Sensor disabled | Cyberhaven disabled this Sensor with a remote configuration policy. Contact support if you want to enable it. |
| win_process_was_terminated | Requires Attention | Sensor process terminated | The Sensor is no longer running because its process was terminated. Check that the Sensor paths are excluded in any EDR tools and restart the Cyberhaven service. |
| file_was_created | Requires Attention | Compromised Sensor integrity | An unrecognized file was created in a protected folder. Reinstall the Sensor. |
| registry_was_compromised | Requires Attention | Compromised Sensor integrity | A protected registry key was modified. Reinstall the Sensor. |
| uninstall_wrong_password | Healthy | Uninstall attempt | Failed uninstall attempt due to incorrect password. |
| safari_extension_needs_update | Requires Attention | Outdated Safari extension | This endpoint is not running the latest browser extension, indicating that auto-updating may be disabled. Enable extension auto-updating or manually deploy the latest version. |
| sensor_downtime_limit_was_reached | Requires Attention | Non-functional Sensor | The Sensor was non-functional for over "service_downtime_period" seconds. When the Sensor is functional again, this message will automatically disappear at "expiration_timeout" seconds after the outage began. Contact support to adjust the values of "service_downtime_period" and "expiration_timeout". |
| macos_profile_not_compatible | Requires Attention | Non-functional Sensor | Missing or outdated MDM profile. Consult the documentation to install the latest Cyberhaven MDM profile. |
| win_driver_start_error | Requires Attention | Compromised Sensor integrity | The Cyberhaven driver failed to load. Reinstall the sensor to resolve this issue. If the problem persists, contact support. |
| uninstall_success_with_password | Inactive | Uninstalled Sensor | The Sensor was password-protected and was uninstalled. |
| macos_profile_not_found | Requires Attention | Non-functional Sensor | Missing or outdated MDM profile. Consult the documentation to install the latest Cyberhaven MDM profile. |
| macos_profile_removed_or_manual_install | Requires Attention | Non-functional Sensor | Missing or outdated MDM profile. Consult the documentation to install the latest Cyberhaven MDM profile. |
| win_outlook_exchange_cache_disabled | Requires Attention | Outlook plugin stopped | Enable Cached Exchange Mode in Outlook and restart it. Consult the documentation for additional details. |
| win_outlook_plugin_disabled | Requires Attention | Outlook plugin disabled | Consult the Outlook plugin documentation to troubleshoot this issue. |
| win_outlook_restart_required | Requires Attention | Outlook plugin stopped | Restart Outlook and consult the documentation for additional details. |
| win_outlook_plugin_crashed | Requires Attention | Outlook plugin crashed | Consult the Outlook plugin documentation to troubleshoot this issue. |
| firefox_extension_not_installed_by_config | Healthy | Disabled Firefox Extension | The Cyberhaven Firefox browser extension has been disabled by a configuration setting. A configuration change is required to reenable, contact support for further assistance. |
| chrome_extension_not_installed_by_config Healthy | Disabled Chrome Extension | The Cyberhaven Chrome browser extension has been disabled by a configuration setting. A configuration change is required to reenable, contact support for further assistance. | |
| msedge_extension_not_installed_by_config Healthy | Disabled Edge Extension | The Cyberhaven Edge browser extension has been disabled by a configuration setting. A configuration change is required to reenable, contact support for further assistance. | |
| win_driver_disabled_by_safeguards | Requires Attention | Non-functional Sensor | The Cyberhaven driver was disabled due to excessive system failures. A configuration change is required to reenable it, contact support for further assistance. |
| win_excel_plugin_crashed | Requires Attention | Excel plugin crashed | Consult the Excel plugin documentation to troubleshoot this issue. |
| win_excel_plugin_disabled | Requires Attention | Excel plugin disabled | Consult the Excel plugin documentation to troubleshoot this issue. |
| win_excel_restart_required | Requires Attention | Excel plugin stopped | Restart Excel and consult the documentation for additional details. |
| win_powerpoint_plugin_crashed | Requires Attention | Powerpoint plugin crashed | Consult the Powerpoint plugin documentation to troubleshoot this issue. |
| win_powerpoint_plugin_disabled | Requires Attention | Powerpoint plugin disabled | Consult the Powerpoint plugin documentation to troubleshoot this issue. |
| win_powerpoint_restart_required | Requires Attention | Powerpoint plugin stopped | Restart PowerPoint and consult the documentation for additional details. |
| win_word_plugin_crashed | Requires Attention | Word plugin crashed | Consult the Word plugin documentation documentation to troubleshoot this issue. |
| win_word_plugin_disabled | Requires Attention | Word plugin disabled | Consult the Word plugin documentation to troubleshoot this issue. |
| win_word_restart_required | Requires Attention | Word plugin stopped | Restart Word and consult the documentation for additional details. |